sodium-native
Advanced tools
The sodium-native package provides native bindings to the libsodium library, which is a modern, easy-to-use software library for encryption, decryption, signatures, password hashing, and more.
Encryption and Decryption
This feature allows you to encrypt and decrypt messages using secret-key cryptography. The code sample demonstrates how to encrypt a message and then decrypt it back to its original form.
const sodium = require('sodium-native');
const message = Buffer.from('Hello, World!');
const cipher = Buffer.alloc(message.length + sodium.crypto_secretbox_MACBYTES);
const nonce = Buffer.alloc(sodium.crypto_secretbox_NONCEBYTES);
const key = Buffer.alloc(sodium.crypto_secretbox_KEYBYTES);
sodium.randombytes_buf(nonce);
sodium.randombytes_buf(key);
sodium.crypto_secretbox_easy(cipher, message, nonce, key);
const decrypted = Buffer.alloc(message.length);
if (!sodium.crypto_secretbox_open_easy(decrypted, cipher, nonce, key)) {
throw new Error('Decryption failed');
}
console.log(decrypted.toString());Hashing
This feature allows you to hash data using a cryptographic hash function. The code sample demonstrates how to hash a message and output the hash in hexadecimal format.
const sodium = require('sodium-native');
const input = Buffer.from('Hello, World!');
const output = Buffer.alloc(sodium.crypto_generichash_BYTES);
sodium.crypto_generichash(output, input);
console.log(output.toString('hex'));Key Derivation
This feature allows you to derive subkeys from a master key using a key derivation function. The code sample demonstrates how to derive a subkey from a master key.
const sodium = require('sodium-native');
const masterKey = Buffer.alloc(sodium.crypto_kdf_KEYBYTES);
sodium.randombytes_buf(masterKey);
const subKey = Buffer.alloc(sodium.crypto_kdf_BYTES_MIN);
sodium.crypto_kdf_derive_from_key(subKey, 1, 'context', masterKey);
console.log(subKey.toString('hex'));Digital Signatures
This feature allows you to create and verify digital signatures. The code sample demonstrates how to generate a key pair, sign a message, and verify the signature.
const sodium = require('sodium-native');
const message = Buffer.from('Hello, World!');
const publicKey = Buffer.alloc(sodium.crypto_sign_PUBLICKEYBYTES);
const secretKey = Buffer.alloc(sodium.crypto_sign_SECRETKEYBYTES);
sodium.crypto_sign_keypair(publicKey, secretKey);
const signature = Buffer.alloc(sodium.crypto_sign_BYTES);
sodium.crypto_sign_detached(signature, message, secretKey);
if (sodium.crypto_sign_verify_detached(signature, message, publicKey)) {
console.log('Signature is valid');
} else {
console.log('Signature is invalid');
}libsodium-wrappers is a JavaScript wrapper for the libsodium library, providing similar functionalities to sodium-native but with a focus on ease of use and compatibility with web environments. It is built on top of the WebAssembly version of libsodium, making it suitable for both Node.js and browser environments.
tweetnacl is a cryptographic library that provides a subset of the functionalities offered by sodium-native. It is a smaller, self-contained library that is easy to use and suitable for environments where a smaller footprint is required. However, it does not offer the same breadth of features as sodium-native.
The built-in crypto module in Node.js provides various cryptographic functionalities, including hashing, encryption, and digital signatures. While it is not as comprehensive as sodium-native, it is a good alternative for basic cryptographic needs and does not require any additional dependencies.
Low level bindings for libsodium.
npm install sodium-native
The goal of this project is to be thin, stable, unopionated wrapper around libsodium.
All methods exposed are more or less a direct translation of the libsodium c-api. This means that most data types are buffers and you have to manage allocating return values and passing them in as arguments intead of receiving them as return values.
This makes this API harder to use than other libsodium wrappers out there, but also means that you'll be able to get a lot of perf / memory improvements as you can do stuff like inline encryption / decryption, re-use buffers etc.
This also makes this library useful as a foundation for more high level crypto abstractions that you want to make.
var sodium = require('sodium-native')
var nonce = Buffer.alloc(sodium.crypto_secretbox_NONCEBYTES)
var key = sodium.sodium_malloc(sodium.crypto_secretbox_KEYBYTES) // secure buffer
var message = Buffer.from('Hello, World!')
var ciphertext = Buffer.alloc(message.length + sodium.crypto_secretbox_MACBYTES)
sodium.randombytes_buf(nonce) // insert random data into nonce
sodium.randombytes_buf(key) // insert random data into key
// encrypted message is stored in ciphertext.
sodium.crypto_secretbox_easy(ciphertext, message, nonce, key)
console.log('Encrypted message:', ciphertext)
var plainText = Buffer.alloc(ciphertext.length - sodium.crypto_secretbox_MACBYTES)
if (!sodium.crypto_secretbox_open_easy(plainText, ciphertext, nonce, key)) {
console.log('Decryption failed!')
} else {
console.log('Decrypted message:', plainText, '(' + plainText.toString() + ')')
}
Go to docs for the latest release (The following docs may be for a unreleased version)
var sodium = require('sodium-native')Loads the bindings. If you get an module version error you probably need to reinstall the module because you switched node versions.
Bindings to the secure memory API. See the libsodium "Securing memory allocations" docs for more information.
sodium.sodium_memzero(buffer)Zero out the data in buffer.
sodium.sodium_mlock(buffer)Lock the memory contained in buffer
sodium.sodium_munlock(buffer)Unlock previously sodium_mlocked memory contained in buffer. This will also sodium_memzero buffer
var buffer = sodium.sodium_malloc(size)Allocate a buffer of size which is memory protected. See libsodium docs for details. Be aware that many Buffer methods may break the security guarantees of sodium.sodium_malloc'ed memory. To check if a Buffer is a "secure" buffer,
you can call access the getter buffer.secure which will be true.
sodium.sodium_mprotect_noaccess(buffer)Make buffer allocated using sodium.sodium_malloc inaccessible, crashing the process if any access is attempted.
Note that this will have no effect for normal Buffers.
sodium.sodium_mprotect_readonly(buffer)Make buffer allocated using sodium.sodium_malloc read-only, crashing the process if any writing is attempted.
Note that this will have no effect for normal Buffers.
sodium.sodium_mprotect_readwrite(buffer)Make buffer allocated using sodium.sodium_malloc read-write, undoing sodium_mprotect_noaccess or sodium_mprotect_readonly.
Note that this will have no effect for normal Buffers.
Bindings to the random data generation API. See the libsodium randombytes docs for more information.
var uint32 = sodium.randombytes_random()Generate a random 32-bit unsigned integer [0, 0xffffffff] (both inclusive)
var uint = sodium.randombytes_uniform(upper_bound)Generate a random 32-bit unsigned integer [0, upper_bound) (last exclusive).
upper_bound must be 0xffffffff at most.
sodium.randombytes_buf(buffer)Fill buffer with random data.
sodium.randombytes_buf_deterministic(buffer, seed)Fill buffer with random data, generated from seed. seed must be a Buffer
of at least sodium.randombytes_SEEDBYTES length
Bindings to various helper functions. See the libsodium helpers docs for more information.
var bool = sodium.sodium_memcmp(b1, b2)Compare b1 with b2, in constant-time for b1.length.
b1 must be Bufferb2 must be Buffer and must be b1.length bytesReturns true when equal, otherwise false.
var direction = sodium.sodium_compare(b1, b2)Compare b1 with b2, regarding either as little-endian encoded number.
b1 must be Bufferb2 must be Buffer and must be b1.length bytesReturns 1, 0 or -1 on whether b1 is greater, equal or less than b2.
This is the same scheme as Array.prototype.sort expect.
sodium.sodium_add(a, b)Adds b to a (wrapping), regarding either as little-endian encoded number,
and writing the result into a.
a must be Bufferb must be Buffer and must be a.length bytessodium.sodium_sub(a, b)Subtractss b from a (wrapping), regarding either as little-endian encoded
number, and writing the result into a.
a must be Bufferb must be Buffer and must be a.length bytessodium.sodium_increment(buf)Increment buf as a little-endian number. This operation is constant-time
for the length of buf.
buf must be Buffervar bool = sodium.sodium_is_zero(buf, len)Test whether buf is all zero for len bytes. This operation is
constant-time for len.
len must be integer at most the length of bufReturns true if all len bytes are zero, otherwise false.
Bindings to the padding API. See the libsodium padding docs for more information.
var paddedLength = sodium.sodium_pad(buf, unpaddedLength, blocksize)Pad buf with random data from index unpaddedLength up to closest multiple of
blocksize.
buf must be Bufferunpadded_buflen must be integer at most buf.lengthblocksize must be integer greater than 1 but at most buf.lengthReturns the length of the padded data (so you may .slice the buffer to here).
var unpaddedLength = sodium.sodium_unpad(buf, paddedLength, blocksize)Calculate unpaddedLength from a padded buf with blocksize
buf must be Bufferpadded_buflen must be integer at most buf.lengthblocksize must be integer greater than 1 but at most buf.lengthReturns the length of the unpadded data (so you may .slice the buffer to here).
Bindings for the crypto_sign API. See the libsodium crypto_sign docs for more information.
crypto_sign_seed_keypair(publicKey, secretKey, seed)Create a new keypair based on a seed.
publicKey should be a buffer with length crypto_sign_PUBLICKEYBYTES.secretKey should be a buffer with length crypto_sign_SECRETKEYBYTES.seed should be a buffer with length crypto_sign_SEEDBYTES.The generated public and secret key will be stored in passed in buffers.
crypto_sign_keypair(publicKey, secretKey)Create a new keypair.
publicKey should be a buffer with length crypto_sign_PUBLICKEYBYTES.secretKey should be a buffer with length crypto_sign_SECRETKEYBYTES.The generated public and secret key will be stored in passed in buffers.
crypto_sign(signedMessage, message, secretKey)Sign a message.
signedMessage should be a buffer with length crypto_sign_BYTES + message.length.message should be a buffer of any length.secretKey should be a secret key.The generated signed message will be stored in signedMessage.
var bool = crypto_sign_open(message, signedMessage, publicKey)Verify and open a message.
message should be a buffer with length signedMessage.length - crypto_sign_BYTES.signedMessage at least crypto_sign_BYTES length.publicKey should be a public key.Will return true if the message could be verified. Otherwise false.
If verified the originally signed message is stored in the message buffer.
crypto_sign_detached(signature, message, secretKey)Same as crypto_sign except it only stores the signature.
signature should be a buffer with length crypto_sign_BYTES.message should be a buffer of any length.secretKey should be a secret key.The generated signature is stored in signature.
var bool = crypto_sign_verify_detached(signature, message, publicKey)Verify a signature.
signature should be a buffer with length crypto_sign_BYTES.message should be a buffer of any length.publicKey should be a public key.Will return true if the message could be verified. Otherwise false.
crypto_sign_ed25519_pk_to_curve25519(curve_pk, ed_pk)Convert an ed25519 public key to curve25519 (which can be used with box and scalarmult)
curve_pk should be a buffer with length crypto_box_PUBLICKEYBYTESed_pk should be a buffer with length crypto_sign_PUBLICKEYBYTEScrypto_sign_ed25519_sk_to_curve25519(curve_sk, ed_sk)Convert an ed25519 secret key to curve25519 (which can be used with box and scalarmult)
curve_sk should be a buffer with length crypto_box_SECRETKEYBYTESed_sk should be a buffer with length crypto_sign_SECRETKEYBYTEScrypto_sign_ed25519_sk_to_pk(pk, sk)Extract an ed25519 public key from an ed25519 secret key
pk must be Buffer of at least crypto_sign_PUBLICKEYBYTES bytessk must be Buffer of at least crypto_sign_SECRETKEYBYTES bytesBindings for the crypto_generichash API. See the libsodium crypto_generichash docs for more information.
crypto_generichash(output, input, [key])Hash a value with an optional key using the generichash method.
output should be a buffer with length within crypto_generichash_BYTES_MIN - crypto_generichash_BYTES_MAX.input should be a buffer of any length.key is an optional buffer of length within crypto_generichash_KEYBYTES_MIN - crypto_generichash_KEYBYTES_MAX.The generated hash is stored in output.
Also exposes crypto_generichash_BYTES and crypto_generichash_KEYBYTES that can be used as "default" buffer sizes.
crypto_generichash_batch(output, inputArray, [key])Same as crypto_generichash except this hashes an array of buffers instead of a single one.
var instance = crypto_generichash_instance([key], [outputLength])Create a generichash instance that can hash a stream of input buffers.
key is an optional buffer as above.outputLength the buffer size of your output.instance.update(input)Update the instance with a new piece of data.
input should be a buffer of any size.instance.final(output)Finalize the instance.
output should be a buffer as above with the same length you gave when creating the instance.The generated hash is stored in output.
Bindings for the crypto_box API. See the libsodium crypto_box docs for more information.
crypto_box_seed_keypair(publicKey, secretKey, seed)Create a new keypair based on a seed.
publicKey should be a buffer with length crypto_box_PUBLICKEYBYTES.secretKey should be a buffer with length crypto_box_SECRETKEYBYTES.seed should be a buffer with length crypto_box_SEEDBYTES.The generated public and secret key will be stored in passed in buffers.
crypto_box_keypair(publicKey, secretKey)Create a new keypair.
publicKey should be a buffer with length crypto_box_PUBLICKEYBYTES.secretKey should be a buffer with length crypto_box_SECRETKEYBYTES.The generated public and secret key will be stored in passed in buffers.
crypto_box_detached(ciphertext, mac, message, nonce, publicKey, secretKey)Encrypt a message.
ciphertext should be a buffer with length message.length.mac should be a buffer with length crypto_box_MACBYTES.message should be a buffer of any length.nonce should be a buffer with length crypto_box_NONCEBYTES.publicKey should be a public key.secretKey should be a secret key.The encrypted message will be stored in ciphertext and the authentification code will be stored in mac.
crypto_box_easy(ciphertext, message, nonce, publicKey, secretKey)Same as crypto_box_detached except it encodes the mac in the message.
ciphertext should be a buffer with length message.length + crypto_box_MACBYTES.message should be a buffer of any length.nonce should be a buffer with length crypto_box_NONCEBYTES.publicKey should be a public key.secretKey should be a secret key.The encrypted message and authentification code will be stored in ciphertext.
var bool = crypto_box_open_detached(message, ciphertext, mac, nonce, publicKey, secretKey)Decrypt a message.
message should be a buffer with length ciphertext.length.mac should be a buffer with length crypto_box_MACBYTES.ciphertext should be a buffer of any length.nonce should be a buffer with length crypto_box_NONCEBYTES.publicKey should be a public key.secretKey should be a secret key.Returns true if the message could be decrypted. Otherwise false.
The decrypted message will be stored in message.
var bool = crypto_box_open_easy(message, ciphertext, nonce, publicKey, secretKey)Decrypt a message encoded with the easy method.
message should be a buffer with length ciphertext.length - crypto_box_MACBYTES.ciphertext should be a buffer with length at least crypto_box_MACBYTES.nonce should be a buffer with length crypto_box_NONCEBYTES.publicKey should be a public key.secretKey should be a secret key.Returns true if the message could be decrypted. Otherwise false.
The decrypted message will be stored in message.
Bindings for the crypto_box_seal API. See the libsodium crypto_box_seal docs for more information.
Keypairs can be generated with crypto_box_keypair() or crypto_box_seed_keypair().
crypto_box_seal(ciphertext, message, publicKey)Encrypt a message in a sealed box using a throwaway keypair. The ciphertext cannot be associated with the sender due to the sender's key being a single use keypair that is overwritten during encryption.
ciphertext should be a buffer with length at least message.length + crypto_box_SEALBYTES.message should be a buffer with any length.publicKey should be the receipent's public key.var bool = crypto_box_seal_open(message, ciphertext, publicKey, secretKey)Decrypt a message encoded with the sealed box method.
message should be a buffer with length at least ciphertext.length - crypto_box_SEALBYTES.ciphertext should be a buffer with length at least crypto_box_SEALBYTES.publicKey should be the receipient's public key.secretKey should be the receipient's secret key.Note: the keypair of the recipient is required here, both public and secret key.
This is because during encryption the recipient's public key is used to generate
the nonce. The throwaway public key generated by the sender is stored in the first
crypto_box_PUBLICKEYBYTE's of the ciphertext.
Bindings for the crypto_secretbox API. See the libsodium crypto_secretbox docs for more information.
crypto_secretbox_detached(ciphertext, mac, message, nonce, secretKey)Encrypt a message.
ciphertext should be a buffer with length message.length.mac should be a buffer with length crypto_secretbox_MACBYTES.message should be a buffer of any length.nonce should be a buffer with length crypto_secretbox_NONCEBYTES.secretKey should be a secret key with length crypto_secretbox_KEYBYTES.The encrypted message will be stored in ciphertext and the authentification code will be stored in mac.
crypto_secretbox_easy(ciphertext, message, nonce, secretKey)Same as crypto_secretbox_detached except it encodes the mac in the message.
ciphertext should be a buffer with length message.length + crypto_secretbox_MACBYTES.message should be a buffer of any length.nonce should be a buffer with length crypto_secretbox_NONCEBYTES.secretKey should be a secret key with length crypto_secretbox_KEYBYTES.var bool = crypto_secretbox_open_detached(message, ciphertext, mac, nonce, secretKey)Decrypt a message.
message should be a buffer with length ciphertext.length.mac should be a buffer with length crypto_secretbox_MACBYTES.ciphertext should be a buffer of any length.nonce should be a buffer with length crypto_secretbox_NONCEBYTES.secretKey should be a secret key.Returns true if the message could be decrypted. Otherwise false.
The decrypted message will be stored in message.
var bool = crypto_secretbox_open_easy(message, ciphertext, nonce, secretKey)Decrypt a message encoded with the easy method.
message should be a buffer with length ciphertext.length - crypto_secretbox_MACBYTES.ciphertext should be a buffer with length at least crypto_secretbox_MACBYTES.nonce should be a buffer with length crypto_secretbox_NONCEBYTES.secretKey should be a secret key.Returns true if the message could be decrypted. Otherwise false.
The decrypted message will be stored in message.
Bindings for the crypto_aead_* APIs. See the libsodium AEAD docs for more information.
Currently only crypto_aead_xchacha20poly1305_ietf is exposed.
crypto_aead_xchacha20poly1305_ietf_ABYTEScrypto_aead_xchacha20poly1305_ietf_KEYBYTEScrypto_aead_xchacha20poly1305_ietf_NPUBBYTEScrypto_aead_xchacha20poly1305_ietf_NSECBYTEScrypto_aead_xchacha20poly1305_ietf_MESSAGEBYTES_MAX - Note this is Number.MAX_SAFE_INTEGER for nowcrypto_aead_xchacha20poly1305_ietf_keygen(key)Generate a new encryption key.
key should be a buffer of length crypto_aead_xchacha20poly1305_ietf_KEYBYTES.The generated key is stored in key.
var clen = crypto_aead_xchacha20poly1305_ietf_encrypt(ciphertext, message, [ad], null, npub, key)Encrypt a message with (npub, key) and optional additional data ad.
ciphertext should be a Buffer of size
message.length + crypto_aead_xchacha20poly1305_ietf_ABYTES.message should be a Buffer.ad is optional and should be null or Buffer. Included in the computation
of authentication tag appended to the message.null is in the position of the unused nsec argument. This should always be
null.npub should be Buffer of length crypto_aead_xchacha20poly1305_ietf_NPUBBYTES.key should be a Buffer of length crypto_aead_xchacha20poly1305_ietf_KEYBYTES.Returns how many bytes were written to ciphertext. Note that in-place
encryption is possible.
var mlen = crypto_aead_xchacha20poly1305_ietf_decrypt(message, null, ciphertext, [ad], npub, key)Decrypt a message with (npub, key) and optional additional data ad.
message should be a Buffer of size
ciphertext.length - crypto_aead_xchacha20poly1305_ietf_ABYTES.null is in the position of the unused nsec argument. This should always be
null.ciphertext should be a Buffer.ad is optional and should be null or Buffer. Included in the computation
of authentication tag appended to the message.npub should be Buffer of length crypto_aead_xchacha20poly1305_ietf_NPUBBYTES.key should be a Buffer of length crypto_aead_xchacha20poly1305_ietf_KEYBYTES.Returns how many bytes were written to message. Note that in-place
encryption is possible.
var maclen = crypto_aead_xchacha20poly1305_ietf_encrypt_detached(ciphertext, mac, message, [ad], null, npub, key)Encrypt a message with (npub, key) and optional additional data ad.
ciphertext should be a Buffer of size message.length.mac should be Buffer of size crypto_aead_xchacha20poly1305_ietf_ABYTES.message should be a Buffer.ad is optional and should be null or Buffer. Included in the computation
of authentication tag appended to the message.null is in the position of the unused nsec argument. This should always be
null.npub should be Buffer of length crypto_aead_xchacha20poly1305_ietf_NPUBBYTES.key should be a Buffer of length crypto_aead_xchacha20poly1305_ietf_KEYBYTES.Returns how many bytes were written to mac. Note that in-place
encryption is possible.
crypto_aead_xchacha20poly1305_ietf_decrypt_detached(message, null, ciphertext, mac, [ad], npub, key)Decrypt a message with (npub, key) and optional additional data ad.
message should be a Buffer of size ciphertext.length.null is in the position of the unused nsec argument. This should always be
null.ciphertext should be a Buffer.mac should be Buffer of size crypto_aead_xchacha20poly1305_ietf_ABYTES.ad is optional and should be null or Buffer. Included in the computation
of authentication tag appended to the message.npub should be Buffer of length crypto_aead_xchacha20poly1305_ietf_NPUBBYTES.key should be a Buffer of length crypto_aead_xchacha20poly1305_ietf_KEYBYTES.Returns nothing, but will throw on in case the MAC cannot be authenticated. Note that in-place encryption is possible.
Bindings for the crypto_stream API. See the libsodium crypto_stream docs for more information.
crypto_stream(ciphertext, nonce, key)Generate random data based on a nonce and key into the ciphertext.
ciphertext should be a buffer of any size.nonce should be a buffer with length crypto_stream_NONCEBYTES.key should be a secret key with length crypto_stream_KEYBYTES.The generated data is stored in ciphertext.
crypto_stream_xor(ciphertext, message, nonce, key) orcrypto_stream_chacha20_xor(ciphertext, message, nonce, key)Encrypt, but not authenticate, a message based on a nonce and key
ciphertext should be a buffer with length message.length.message should be a buffer of any size.nonce should be a buffer with length crypto_stream_NONCEBYTES.key should be a secret key with length crypto_stream_KEYBYTES.The encrypted data is stored in ciphertext. To decrypt, swap ciphertext and message.
Also supports in-place encryption where you use the same buffer as ciphertext and message.
Encryption defaults to XSalsa20, use crypto_stream_chacha20_xor if you want
to encrypt/decrypt with ChaCha20 instead.
var instance = crypto_stream_xor_instance(nonce, key) orvar instance = crypto_stream_chacha20_xor_instance(nonce, key)A streaming instance to the crypto_stream_xor api. Pass a nonce and key in the constructor.
Encryption defaults to XSalsa20, use crypto_stream_chacha20_xor_instance if
you want to encrypt/decrypt with ChaCha20 instead.
instance.update(ciphertext, message)Encrypt the next message
instance.final()Finalize the stream. Zeros out internal state.
Bindings for the crypto_auth API. See the libsodium crypto_auth docs for more information.
crypto_auth(output, input, key)Create an authentication token.
output should be a buffer of length crypto_auth_BYTES.input should be a buffer of any size.key should be a buffer of length crypto_auth_KEYBYTES.The generated token is stored in output.
var bool = crypto_auth_verify(output, input, key)Verify a token.
output should be a buffer of length crypto_auth_BYTES.input should be a buffer of any size.key should be a buffer of length crypto_auth_KEYBYTES.Returns true if the token could be verified. Otherwise false.
Bindings for the crypto_secretstream API. See the libsodium crypto_secretstream docs for more information.
crypto_secretstream_xchacha20poly1305_ABYTEScrypto_secretstream_xchacha20poly1305_HEADERBYTEScrypto_secretstream_xchacha20poly1305_KEYBYTEScrypto_secretstream_xchacha20poly1305_MESSAGEBYTES_MAXcrypto_secretstream_xchacha20poly1305_TAGBYTES - NOTE: Unofficial constantBuffer)crypto_secretstream_xchacha20poly1305_TAG_MESSAGEcrypto_secretstream_xchacha20poly1305_TAG_PUSHcrypto_secretstream_xchacha20poly1305_TAG_REKEYcrypto_secretstream_xchacha20poly1305_TAG_FINALcrypto_secretstream_xchacha20poly1305_keygen(key)Generate a new encryption key.
key should be a buffer of length crypto_secretstream_xchacha20poly1305_KEYBYTES.The generated key is stored in key.
var state = crypto_secretstream_xchacha20poly1305_state_new()Create a new stream state. Returns an opaque object used in the next methods.
crypto_secretstream_xchacha20poly1305_init_push(state, header, key)Initialise state from the writer side with message header and
encryption key key. The header must be sent or stored with the stream.
The key must be exchanged securely with the receiving / reading side.
state should be an opaque state object.header should be a buffer of size crypto_secretstream_xchacha20poly1305_HEADERBYTES.key should be a buffer of length crypto_secretstream_xchacha20poly1305_KEYBYTES.var mlen = crypto_secretstream_xchacha20poly1305_push(state, ciphertext, message, [ad], tag)Encrypt a message with a certain tag and optional additional data ad.
state should be an opaque state object.ciphertext should be a buffer of size message.length + crypto_secretstream_xchacha20poly1305_ABYTES.message should be a buffer.ad is optional and should be null or Buffer. Included in the computation
of authentication tag appended to the message.tag should be Buffer of length crypto_secretstream_xchacha20poly1305_TAGBYTESNote that tag should be one of the crypto_secretstream_xchacha20poly1305_TAG_* constants.
Returns number of encrypted bytes written to ciphertext.
crypto_secretstream_xchacha20poly1305_init_pull(state, header, key)Initialise state from the reader side with message header and
encryption key key. The header must be retrieved from somewhere.
The key must be exchanged securely with the sending / writing side.
state should be an opaque state object.header should be a buffer of size crypto_secretstream_xchacha20poly1305_HEADERBYTES.key should be a buffer of length crypto_secretstream_xchacha20poly1305_KEYBYTES.var clen = crypto_secretstream_xchacha20poly1305_pull(state, message, tag, ciphertext, [ad])Decrypt a message with optional additional data ad, and write message tag to
tag. Make sure to check this!
state should be an opaque state object.message should be a buffer of size ciphertext.length - crypto_secretstream_xchacha20poly1305_ABYTES.tag should be a buffer of crypto_secretstream_xchacha20poly1305_TAGBYTES.ad is optional and should be null or Buffer. Included in the computation
of the authentication tag appended to the message.Note that tag should be one of the crypto_secretstream_xchacha20poly1305_TAG_* constants.
Returns number of decrypted bytes written to message.
crypto_secretstream_xchacha20poly1305_rekey(state)Rekey the opaque state object.
Bindings for the crypto_onetimeauth API. See the libsodium crypto_onetimeauth docs for more information.
crypto_onetimeauth(output, input, key)Create a authentication token based on a onetime key.
output should be a buffer of length crypto_onetimauth_BYTES.input should be a buffer of any size.key should be a buffer of length crypto_onetimeauth_KEYBYTES.The generated token is stored in output.
var bool = crypto_onetimeauth_verify(output, input, key)Verify a token.
output should be a buffer of length crypto_onetimeauth_BYTES.input should be a buffer of any size.key should be a buffer of length crypto_onetimeauth_KEYBYTES.Returns true if the token could be verified. Otherwise false.
var instance = crypto_onetimeauth_instance(key)Create an instance that create a token from a onetime key and a stream of input data.
key should be a buffer of length crypto_onetimeauth_KEYBYTES.instance.update(input)Update the instance with a new piece of data.
input should be a buffer of any size.instance.final(output)Finalize the instance.
output should be a buffer of length crypto_onetimeauth_BYTES.The generated hash is stored in output.
Bindings for the crypto_pwhash API. See the libsodium crypto_pwhash docs for more information.
crypto_pwhash(output, password, salt, opslimit, memlimit, algorithm)Create a password hash.
output should be a buffer with length within crypto_pwhash_BYTES_MIN - crypto_pwhash_BYTES_MAX.password should be a buffer of any size.salt should be a buffer with length crypto_pwhash_SALTBYTES.opslimit should a be number containing your ops limit setting in the range crypto_pwhash_OPSLIMIT_MIN - crypto_pwhash_OPSLIMIT_MAX.memlimit should a be number containing your mem limit setting in the range crypto_pwhash_MEMLIMIT_MIN - crypto_pwhash_OPSLIMIT_MAX.algorithm should be a number specifying the algorithm you want to use.Available default ops and mem limits are
crypto_pwhash_OPSLIMIT_INTERACTIVEcrypto_pwhash_OPSLIMIT_MODERATEcrypto_pwhash_OPSLIMIT_SENSITIVEcrypto_pwhash_MEMLIMIT_INTERACTIVEcrypto_pwhash_MEMLIMIT_MODERATEcrypto_pwhash_MEMLIMIT_SENSITIVEThe available algorithms are
crypto_pwhash_ALG_DEFAULTcrypto_pwhash_ALG_ARGON2ID13crypto_pwhash_ALG_ARGON2I13The generated hash will be stored in output and the entire output buffer will be used.
crypto_pwhash_str(output, password, opslimit, memlimit)Create a password hash with a random salt.
output should be a buffer with length crypto_pwhash_STRBYTES.password should be a buffer of any size.opslimit should a be number containing your ops limit setting in the range crypto_pwhash_OPSLIMIT_MIN - crypto_pwhash_OPSLIMIT_MAX.memlimit should a be number containing your mem limit setting in the range crypto_pwhash_MEMLIMIT_MIN - crypto_pwhash_OPSLIMIT_MAX.The generated hash, settings, salt, version and algorithm will be stored in output and the entire output buffer will be used.
var bool = crypto_pwhash_str_verify(str, password)Verify a password hash generated with the above method.
str should be a buffer with length crypto_pwhash_STRBYTES.password should be a buffer of any size.Returns true if the hash could be verified with the settings contained in str. Otherwise false.
var bool = crypto_pwhash_str_needs_rehash(hash, opslimit, memlimit)Check if a password hash needs rehash, either because the default algorithm changed, opslimit or memlimit increased or because the hash is malformed.
hash should be a buffer with length crypto_pwhash_STRBYTES.opslimit should a be number containing your ops limit setting in the range crypto_pwhash_OPSLIMIT_MIN - crypto_pwhash_OPSLIMIT_MAX.memlimit should a be number containing your mem limit setting in the range crypto_pwhash_MEMLIMIT_MIN - crypto_pwhash_OPSLIMIT_MAX.Returns true if the hash should be rehashed the settings contained in str.
Otherwise false if it is still good.
crypto_pwhash_async(output, password, salt, opslimit, memlimit, algorithm, callback)Just like crypto_pwhash but will run password hashing on a separate worker so it will not block the event loop. callback(err) will receive any errors from the hashing but all argument errors will throw. The resulting hash is written to output. This function also supports async_hooks as the type sodium-native:crypto_pwhash_async
crypto_pwhash_str_async(output, password, opslimit, memlimit, callback)Just like crypto_pwhash_str but will run password hashing on a separate worker so it will not block the event loop. callback(err) will receive any errors from the hashing but all argument errors will throw. The resulting hash with parameters is written to output. This function also supports async_hooks as the type sodium-native:crypto_pwhash_str_async
crypto_pwhash_str_verify_async(str, password, callback)Just like crypto_pwhash_str_verify but will run password hashing on a separate worker so it will not block the event loop. callback(err, bool) will receive any errors from the hashing but all argument errors will throw. If the verification succeeds bool is true, otherwise false. Due to an issue with libsodium err is currently never set. This function also supports async_hooks as the type sodium-native:crypto_pwhash_str_verify_async
Bindings for the crypto_pwhash_scryptsalsa208sha256 API. See the libsodium crypto_pwhash_scryptsalsa208sha256 docs for more information.
crypto_pwhash_scryptsalsa208sha256(output, password, salt, opslimit, memlimit)Create a password hash.
output should be a buffer with length within crypto_pwhash_scryptsalsa208sha256_BYTES_MIN - crypto_pwhash_scryptsalsa208sha256_BYTES_MAX.password should be a buffer of any size.salt should be a buffer with length crypto_pwhash_scryptsalsa208sha256_SALTBYTES.opslimit should a be number containing your ops limit setting in the range crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_MIN - crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_MAX.memlimit should a be number containing your mem limit setting in the range crypto_pwhash_scryptsalsa208sha256_MEMLIMIT_MIN - crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_MAX.Available default ops and mem limits are
crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_INTERACTIVEcrypto_pwhash_scryptsalsa208sha256_OPSLIMIT_SENSITIVEcrypto_pwhash_scryptsalsa208sha256_MEMLIMIT_INTERACTIVEcrypto_pwhash_scryptsalsa208sha256_MEMLIMIT_SENSITIVEThe generated hash will be stored in output and the entire output buffer will be used.
crypto_pwhash_scryptsalsa208sha256_str(output, password, opslimit, memlimit)Create a password hash with a random salt.
output should be a buffer with length crypto_pwhash_scryptsalsa208sha256_STRBYTES.password should be a buffer of any size.opslimit should a be number containing your ops limit setting in the range crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_MIN - crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_MAX.memlimit should a be number containing your mem limit setting in the range crypto_pwhash_scryptsalsa208sha256_MEMLIMIT_MIN - crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_MAX.The generated hash, settings, salt, version and algorithm will be stored in output and the entire output buffer will be used.
var bool = crypto_pwhash_scryptsalsa208sha256_str_verify(str, password)Verify a password hash generated with the above method.
str should be a buffer with length crypto_pwhash_scryptsalsa208sha256_STRBYTES.password should be a buffer of any size.Returns true if the hash could be verified with the settings contained in str. Otherwise false.
var bool = crypto_pwhash_scryptsalsa208sha256_str_needs_rehash(hash, opslimit, memlimit)Check if a password hash needs rehash, either because opslimit or memlimit increased or because the hash is malformed.
hash should be a buffer with length crypto_pwhash_scryptsalsa208sha256_STRBYTES.opslimit should a be number containing your ops limit setting in the range crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_MIN - crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_MAX.memlimit should a be number containing your mem limit setting in the range crypto_pwhash_scryptsalsa208sha256_MEMLIMIT_MIN - crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_MAX.Returns true if the hash should be rehashed the settings contained in str.
Otherwise false if it is still good.
crypto_pwhash_scryptsalsa208sha256_async(output, password, salt, opslimit, memlimit, callback)Just like crypto_pwhash_scryptsalsa208sha256 but will run password hashing on a separate worker so it will not block the event loop. callback(err) will receive any errors from the hashing but all argument errors will throw. The resulting hash is written to output. This function also supports async_hooks as the type sodium-native:crypto_pwhash_scryptsalsa208sha256_async
crypto_pwhash_scryptsalsa208sha256_str_async(output, password, opslimit, memlimit, callback)Just like crypto_pwhash_scryptsalsa208sha256_str but will run password hashing on a separate worker so it will not block the event loop. callback(err) will receive any errors from the hashing but all argument errors will throw. The resulting hash with parameters is written to output. This function also supports async_hooks as the type sodium-native:crypto_pwhash_scryptsalsa208sha256_str_async
crypto_pwhash_scryptsalsa208sha256_str_verify_async(str, password, callback)Just like crypto_pwhash_scryptsalsa208sha256_str_verify but will run password hashing on a separate worker so it will not block the event loop. callback(err, bool) will receive any errors from the hashing but all argument errors will throw. If the verification succeeds bool is true, otherwise false. Due to an issue with libsodium err is currently never set. This function also supports async_hooks as the type sodium-native:crypto_pwhash_scryptsalsa208sha256_str_verify_async
Bindings for the crypto_kx API. See the libsodium crypto_kx docs for more information.
crypto_kx_keypair(publicKey, secretKey)Create a key exchange key pair.
publicKey should be a buffer of length crypto_kx_PUBLICKEYBYTES.secretKey should be a buffer of length crypto_kx_SECRETKEYBYTES.crypto_kx_seed_keypair(publicKey, secretKey, seed)Create a key exchange key pair based on a seed.
publicKey should be a buffer of length crypto_kx_PUBLICKEYBYTES.secretKey should be a buffer of length crypto_kx_SECRETKEYBYTES.seed should be a buffer of length crypto_kx_SEEDBYTEScrypto_kx_client_session_keys(rx, tx, clientPublicKey, clientSecretKey, serverPublicKey)Generate a session receive and transmission key for a client. The public / secret keys should be generated using the key pair method above.
rx should be a buffer of length crypto_kx_SESSIONKEYBYTES or null.tx should be a buffer of length crypto_kx_SESSIONKEYBYTES or null.You should use the rx to decrypt incoming data and tx to encrypt outgoing.
If you need to make a one-way or half-duplex channel you can give only one of
rx or tx.
crypto_kx_server_session_keys(rx, tx, serverPublicKey, serverSecretKey, clientPublicKey)Generate a session receive and transmission key for a server. The public / secret keys should be generated using the key pair method above.
rx should be a buffer of length crypto_kx_SESSIONKEYBYTES or null.tx should be a buffer of length crypto_kx_SESSIONKEYBYTES or null.You should use the rx to decrypt incoming data and tx to encrypt outgoing.
If you need to make a one-way or half-duplex channel you can give only one of
rx or tx.
Bindings for the crypto_scalarmult API. See the libsodium crypto_scalarmult docs for more information.
crypto_scalarmult_base(publicKey, secretKey)Create a scalar multiplication public key based on a secret key
publicKey should be a buffer of length crypto_scalarmult_BYTES.secretKey should be a buffer of length crypto_scalarmult_SCALARBYTES.The generated public key is stored in publicKey.
crypto_scalarmult(sharedSecret, secretKey, remotePublicKey)Derive a shared secret from a local secret key and a remote public key.
sharedSecret shoudl be a buffer of length crypto_scalarmult_BYTES.secretKey should be a buffer of length crypto_scalarmult_SCALARBYTES.remotePublicKey should be a buffer of length crypto_scalarmult_BYTES.The generated shared secret is stored in sharedSecret.
Bindings for the crypto_scalarmult_ed25519 and crypto_core_ed25519 API. See the libsodium docs for more information.
crypto_scalarmult_ed25519_BYTEScrypto_scalarmult_ed25519_SCALARBYTEScrypto_core_ed25519_BYTEScrypto_core_ed25519_UNIFORMBYTEScrypto_core_ed25519_SCALARBYTEScrypto_core_ed25519_NONREDUCEDSCALARBYTESvar bool = crypto_core_ed25519_is_valid_point(p)The crypto_core_ed25519_is_valid_point() function checks that p represents a point on the edwards25519 curve, in canonical form, on the main subgroup, and that the point doesn't have a small order.
p must be Buffer of at least crypto_core_ed25519_BYTES bytesReturns true or false
crypto_core_ed25519_from_uniform(p, r)Maps a crypto_core_ed25519_UNIFORMBYTES bytes vector (usually the output of
a hash function) to a a valid curve point and stores its compressed
representation in p.
The point is guaranteed to be on the main subgroup.
p must be Buffer of at least crypto_core_ed25519_BYTES bytesr must be Buffer of at least crypto_core_ed25519_UNIFORMBYTES bytescrypto_scalarmult_ed25519(q, n, p)Multiply point p by scalar n and store its compressed representation in q.
q must be Buffer of at least crypto_scalarmult_ed25519_BYTES bytesn must be Buffer of at least crypto_scalarmult_ed25519_SCALARBYTES bytesp must be Buffer of at least crypto_scalarmult_ed25519_BYTES bytesNote this function will throw if n is zero or p is an invalid curve point.
crypto_scalarmult_ed25519_base(q, n)Multiply the basepoint by scalar n and store its compressed representation in
q. Note that n will be clamped.
q must be Buffer of at least crypto_scalarmult_ed25519_BYTES bytesn must be Buffer of at least crypto_scalarmult_ed25519_SCALARBYTES bytesNote this function will throw if n is zero
crypto_scalarmult_ed25519_noclamp(q, n, p)Multiply point p by scalar n and store its compressed representation in q.
This version does not clamp.
q must be Buffer of at least crypto_scalarmult_ed25519_BYTES bytesn must be Buffer of at least crypto_scalarmult_ed25519_SCALARBYTES bytesp must be Buffer of at least crypto_scalarmult_ed25519_BYTES bytesNote this function will throw if n is zero or p is an invalid curve point.
crypto_scalarmult_ed25519_base_noclamp(q, n)Multiply the basepoint by scalar n and store its compressed representation in
q. This version does not clamp.
q must be Buffer of at least crypto_scalarmult_ed25519_BYTES bytesn must be Buffer of at least crypto_scalarmult_ed25519_SCALARBYTES bytesNote this function will throw if n is zero
crypto_core_ed25519_add(r, p, q)Add point q to p, storing the result to r.
r must be Buffer of at least crypto_core_ed25519_BYTES bytesp must be Buffer of at least crypto_core_ed25519_BYTES bytesq must be Buffer of at least crypto_core_ed25519_BYTES bytesWill throw if p, q are not valid curve points
crypto_core_ed25519_sub(r, p, q)Subtract point q to p, storing the result to r.
r must be Buffer of at least crypto_core_ed25519_BYTES bytesp must be Buffer of at least crypto_core_ed25519_BYTES bytesq must be Buffer of at least crypto_core_ed25519_BYTES bytesWill throw if p, q are not valid curve points
crypto_core_ed25519_scalar_random(r)Generate random scalar in ]0..L[, storing it in r.
r must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytescrypto_core_ed25519_scalar_reduce(r, s)Reduce s mod L, storing it in r.
r must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytess must be Buffer of at least crypto_core_ed25519_NONREDUCEDSCALARBYTES bytescrypto_core_ed25519_scalar_invert(recip, s)Find recip such that s * recip = 1 (mod L), storing it in recip.
recip must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytess must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytescrypto_core_ed25519_scalar_negate(neg, s)Find neg such that s + neg = 0 (mod L), storing it in recip.
recip must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytess must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytescrypto_core_ed25519_scalar_complement(comp, s)Find comp such that s + comp = 1 (mod L), storing it in recip.
comp must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytess must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytescrypto_core_ed25519_scalar_add(z, x, y)Add x and y such that x + y = z (mod L), storing it in z.
x must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytesy must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytesz must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytescrypto_core_ed25519_scalar_sub(z, x, y)Subtract x and y such that x - y = z (mod L), storing it in z.
x must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytesy must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytesz must be Buffer of at least crypto_core_ed25519_SCALARBYTES bytesBindings for the crypto_shorthash API. See the libsodium crypto_shorthash docs for more information.
crypto_shorthash(output, input, key)Hash a value to a short hash based on a key.
output should be a buffer of length crypto_shorthash_BYTES.input should be a buffer of any size.key should be a buffer of length crypto_shorthash_KEYBYTES.The generated short hash is stored in output.
Bindings for the crypto_kdf API. See the libsodium crypto_kdf docs for more information.
crypto_kdf_keygen(key)Generate a new master key.
key should be a buffer of length crypto_kdf_KEYBYTEScrypto_kdf_derive_from_key(subkey, subkeyId, context, key)Derive a new key from a master key.
subkey should be a buffer between crypto_kdf_BYTES_MIN and crypto_kdf_BYTES_MAX.subkeyId should be an integer.context should be a buffer of length crypto_kdf_CONTEXTBYTESkey should by a buffer of length crypto_kdf_KEYBYTEScrypto_hash_sha256(output, input)Hash a value to a short hash based on a key.
output should be a buffer of length crypto_hash_sha256_BYTES.input should be a buffer of any size.The generated short hash is stored in output.
var instance = crypto_hash_sha256_instance()Create an instance that has stream of input data to sha256.
instance.update(input)Update the instance with a new piece of data.
input should be a buffer of any size.instance.final(output)Finalize the instance.
output should be a buffer of length crypto_hash_sha256_BYTES.The generated hash is stored in output.
crypto_hash_sha512(output, input)Hash a value to a short hash based on a key.
output should be a buffer of length crypto_hash_sha512_BYTES.input should be a buffer of any size.The generated short hash is stored in output.
var instance = crypto_hash_sha512_instance()Create an instance that has stream of input data to sha512.
instance.update(input)Update the instance with a new piece of data.
input should be a buffer of any size.instance.final(output)Finalize the instance.
output should be a buffer of length crypto_hash_sha512_BYTES.The generated hash is stored in output.
MIT
FAQs
Low level bindings for libsodium
We found that sodium-native demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.